JavaScript Temporal 달력 변환: 여러 달력 간의 날짜 매핑 마스터하기

세상은 그레고리력만으로 운영되지 않습니다. 전 세계로 사업을 확장하는 기업들은 각기 다른 문화 및 종교적 기념일을 고려해야 하며, 이는 특정 달력 시스템과 연결되어 있습니다. JavaScript의 최신 Temporal API는 이러한 복잡성을 처리할 수 있는 강력한 도구를 제공하여, 개발자가 여러 달력 간의 날짜를 원활하게 매핑하고 정확한 일정 관리, 계산 및 데이터 표시를 보장할 수 있도록 합니다. 이 종합 가이드에서는 Temporal API의 달력 변환 기능을 살펴보고, 글로벌 인식이 가능한 애플리케이션을 구축하기 위한 실용적인 예제와 모범 사례를 제공합니다.

여러 달력 간 날짜 매핑의 필요성 이해하기

기존 JavaScript `Date` 객체는 그레고리력이 아닌 달력을 처리하는 데 한계가 있습니다. Temporal API는 다양한 달력 시스템과 함께 작동하는 표준화되고 견고한 방법을 제공하여 이 문제를 해결합니다. 다음 시나리오를 고려해 보세요:

• 국제 회의 일정 잡기: 그레고리력으로 예정된 이벤트에 해당하는 날짜를 이슬람(히즈라)력이나 히브리력으로 정확하게 파악하는 것은 종교적 휴일과 문화적 민감성을 존중하는 데 매우 중요합니다.
• 다른 지역의 대출 이자 계산: 일부 금융 기관은 이자 계산에 특정 달력을 사용합니다. Temporal을 사용하면 이러한 시스템에서 정확한 날짜 연산이 가능합니다.
• 사용자 선호 형식으로 날짜 표시: 사용자의 로케일과 달력 선호도에 맞춰 날짜 표시를 조정하면 특히 다양한 인구를 대상으로 하는 애플리케이션의 사용자 경험이 향상됩니다.
• 과거 데이터 분석: 과거 데이터 세트로 작업할 때, 오래되거나 덜 일반적인 달력으로 기록된 날짜를 이해하고 변환하는 것은 정확한 해석을 위해 필수적입니다.

Temporal API와 달력 소개

최신 JavaScript 환경에서 널리 지원되는 Temporal API는 날짜, 시간 및 시간대를 다루는 더 직관적이고 강력한 방법을 제공합니다. 핵심적으로 `Temporal.Calendar` 객체는 특정 달력 시스템을 나타냅니다. Temporal.PlainDate, Temporal.PlainDateTime 및 기타 Temporal 타입은 `Temporal.Calendar` 인스턴스와 연결될 수 있습니다.

Temporal API는 현재 (이 글을 쓰는 시점에서) 다음 달력을 지원합니다:

• `iso8601` (그레고리력 - 기본값)
• `gregory` (`iso8601`의 별칭)
• `islamic`
• `islamic-umalqura`
• `islamic-tbla`
• `islamic-rgsa`
• `islamic-civil`
• `hebrew`
• `buddhist`
• `roc` (중화민국력)
• `japanese`
• `persian`

향후 버전에서는 더 많은 달력이 도입되거나 사용자 지정 달력 구현이 허용될 수 있습니다.

Temporal.PlainDate를 사용한 기본 달력 변환

`Temporal.PlainDate` 객체는 시간대 없는 날짜를 나타냅니다. 특정 달력과 연결된 `Temporal.PlainDate`를 생성할 수 있습니다:

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = Temporal.PlainDate.from({ year: 1445, month: 6, day: 8, calendar: islamicCalendar });

console.log(gregorianDate.toString()); // 출력: 2024-01-20
console.log(islamicDate.toString());   // 출력: 1445-06-08[u-ca=islamic]

`toString()` 메서드는 달력 주석 `[u-ca=islamic]`과 함께 날짜를 출력합니다. 이는 해당 날짜가 이슬람력과 관련이 있음을 나타냅니다.

달력 간 변환하기

달력 간 변환의 핵심은 각 달력과 관련된 `Temporal.PlainDate` 객체를 생성한 다음 각 날짜 구성 요소를 추출하는 것입니다. 그레고리력 날짜를 이슬람력의 해당 날짜로 변환하는 방법은 다음과 같습니다:

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');

// 이슬람력의 날짜 구성 요소 추출
const islamicYear = gregorianDate.toPlainDate(islamicCalendar).year;
const islamicMonth = gregorianDate.toPlainDate(islamicCalendar).month;
const islamicDay = gregorianDate.toPlainDate(islamicCalendar).day;

console.log(`Gregorian: ${gregorianDate.toString()}`);
console.log(`Islamic: ${islamicYear}-${islamicMonth}-${islamicDay}`); // 출력: Islamic: 1445-6-8

이 예제를 분석해 보겠습니다:

1. `gregorianDate`를 `Temporal.PlainDate` 객체로 표현하여 시작합니다.
2. `Temporal.Calendar.from('islamic')`를 사용하여 `islamicCalendar` 객체를 생성합니다.
3. 핵심 변환은 `gregorianDate.toPlainDate(islamicCalendar)`에서 발생합니다. 이것은 동일한 시점을 나타내지만 이제 이슬람력과 연결된 새로운 `Temporal.PlainDate` 객체를 생성합니다.
4. 변환된 `Temporal.PlainDate` 객체에서 `year`, `month`, `day` 구성 요소를 추출합니다.

Temporal API에서 지원하는 두 달력 간에 변환하기 위해 이 패턴을 적용할 수 있습니다.

고급 달력 처리: 이슬람력

이슬람력에는 여러 변형이 있습니다. Temporal API는 다음을 지원합니다:

• `islamic`: 일반적인 이슬람력 (구현은 다를 수 있음).
• `islamic-umalqura`: 사우디아라비아의 움 알쿠라력 기반.
• `islamic-tbla`: 표 계산 기반.
• `islamic-rgsa`: 이집트 종교부 산하 사무국 기반.
• `islamic-civil`: 주로 계산에 사용되는 순수 산술 버전의 이슬람력.

이슬람력으로 작업할 때는 사용 사례에 어떤 변형이 적합한지 이해하는 것이 중요합니다. 예를 들어, 사우디아라비아의 종교적 기념일에는 `islamic-umalqura`를 사용하는 것이 좋습니다. 금융 계산의 경우 예측 가능성 때문에 `islamic-civil`이 더 적합할 수 있습니다.

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const islamicUmalquraCalendar = Temporal.Calendar.from('islamic-umalqura');
const islamicCivilCalendar = Temporal.Calendar.from('islamic-civil');

const islamicUmalquraDate = gregorianDate.toPlainDate(islamicUmalquraCalendar);
const islamicCivilDate = gregorianDate.toPlainDate(islamicCivilCalendar);

console.log(`Gregorian: ${gregorianDate.toString()}`);
console.log(`Islamic (Umm al-Qura): ${islamicUmalquraDate.year}-${islamicUmalquraDate.month}-${islamicUmalquraDate.day}`);
console.log(`Islamic (Civil): ${islamicCivilDate.year}-${islamicCivilDate.month}-${islamicCivilDate.day}`);

이슬람력에 대한 중요 고려사항:

• 이슬람력에서 새 달의 시작은 초승달 관측을 기반으로 합니다. `islamic-umalqura` 달력은 사우디아라비아의 실제 달 관측과 일치하는 것을 목표로 하지만, 여전히 불일치가 발생할 수 있습니다.
• `islamic-civil` 달력은 수학적 근사치이며 실제 달 관측을 반영하지 않습니다.
• 이슬람 휴일의 정확한 날짜는 항상 관련 종교 당국이나 신뢰할 수 있는 출처에 문의하십시오.

히브리력으로 작업하기

히브리력은 유대교의 종교적 기념일을 위해 사용되며 이스라엘의 공식 달력이기도 한 태음태양력입니다. 계절과 일치시키기 위해 윤달을 포함합니다.

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const hebrewCalendar = Temporal.Calendar.from('hebrew');

const hebrewDate = gregorianDate.toPlainDate(hebrewCalendar);

console.log(`Gregorian: ${gregorianDate.toString()}`);
console.log(`Hebrew: ${hebrewDate.year}-${hebrewDate.month}-${hebrewDate.day}`);

히브리력 및 Temporal의 주요 특징:

• 윤달은 Temporal API에 의해 자동으로 처리됩니다. 윤년을 결정하거나 추가 달을 더하기 위한 사용자 지정 로직을 구현할 필요가 없습니다.
• 연도 번호는 전통적인 유대교 기원(세상 창조)부터 시작됩니다.
• 히브리력의 월 이름은 그레고리력과 다릅니다. 이러한 월 이름은 국제화(i18n) 라이브러리나 사용자 지정 매핑을 통해 접근할 수 있습니다.

불교력, ROC, 일본력 및 페르시아력 처리

Temporal API는 각각 고유한 특성을 가진 다른 달력들도 지원합니다. 몇 가지 고려사항은 다음과 같습니다:

• 불교력: 불교력은 많은 동남아시아 국가에서 사용되는 태음태양력입니다. 연도 번호는 일반적으로 부처의 열반부터 시작됩니다.
• ROC력 (중화민국력): 이 달력은 대만에서 사용되며 1912년 중화민국 건국부터 연도를 셉니다.
• 일본력: 일본력은 그레고리력을 기반으로 하지만, 연도를 나타내기 위해 일본 연호(nengō)를 사용합니다.
• 페르시아력: 페르시아력은 주로 이란과 아프가니스탄에서 사용되는 태양력입니다.

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const buddhistCalendar = Temporal.Calendar.from('buddhist');
const rocCalendar = Temporal.Calendar.from('roc');
const japaneseCalendar = Temporal.Calendar.from('japanese');
const persianCalendar = Temporal.Calendar.from('persian');

const buddhistDate = gregorianDate.toPlainDate(buddhistCalendar);
const rocDate = gregorianDate.toPlainDate(rocCalendar);
const japaneseDate = gregorianDate.toPlainDate(japaneseCalendar);
const persianDate = gregorianDate.toPlainDate(persianCalendar);

console.log(`Gregorian: ${gregorianDate.toString()}`);
console.log(`Buddhist: ${buddhistDate.year}-${buddhistDate.month}-${buddhistDate.day}`);
console.log(`ROC: ${rocDate.year}-${rocDate.month}-${rocDate.day}`);
console.log(`Japanese: ${japaneseDate.year}-${japaneseDate.month}-${japaneseDate.day}`);
console.log(`Persian: ${persianDate.year}-${persianDate.month}-${persianDate.day}`);

이러한 달력을 사용할 때는 특정 기원(시작 연도)과 날짜 표현과 관련된 문화적 뉘앙스를 인지해야 합니다.

Temporal.Now와 달력 고려사항

`Temporal.Now`를 사용하여 현재 날짜와 시간을 가져올 수 있지만, 기본적으로 ISO 8601 달력의 현재 날짜와 시간을 반환한다는 점을 이해하는 것이 중요합니다. 다른 달력의 현재 날짜가 필요한 경우 변환해야 합니다:

const islamicCalendar = Temporal.Calendar.from('islamic');
const now = Temporal.Now.plainDateISO(); // ISO 8601 달력의 현재 날짜
const islamicNow = now.toPlainDate(islamicCalendar);

console.log(`Current Gregorian Date: ${now.toString()}`);
console.log(`Current Islamic Date: ${islamicNow.year}-${islamicNow.month}-${islamicNow.day}`);

날짜 서식 지정 및 국제화(i18n)

날짜 변환은 방정식의 일부일 뿐입니다. 표시를 위해 올바르게 서식을 지정해야 합니다. JavaScript의 `Intl.DateTimeFormat` API는 강력한 국제화 기능을 제공합니다. 이를 Temporal API와 함께 사용하여 관련 달력을 고려하여 로케일에 맞는 방식으로 날짜 서식을 지정할 수 있습니다.

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = gregorianDate.toPlainDate(islamicCalendar);

const formatter = new Intl.DateTimeFormat('ar-SA-u-ca-islamic', { // 아랍어(사우디아라비아), 이슬람력 사용
  year: 'numeric',
  month: 'long',
  day: 'numeric',
});

console.log(formatter.format(islamicDate)); // 예시 출력: ٢٠ رجب، ١٤٤٥ هـ

코드를 분석해 보겠습니다:

• `'ar-SA-u-ca-islamic'`는 로케일 문자열입니다. `ar-SA`는 아랍어(사우디아라비아)를 지정하고, `u-ca-islamic`은 이슬람력을 명시적으로 요청합니다.
• `Intl.DateTimeFormat` 옵션은 날짜 서식(연, 월, 일)을 제어합니다.
• `format()` 메서드는 `Temporal.PlainDate` 객체(이 경우 `islamicDate`)를 받아 지정된 로케일과 달력에 따라 서식이 지정된 문자열을 반환합니다.

특정 요구에 맞게 로케일 문자열과 서식 옵션을 조정할 수 있습니다. 예를 들어, 날짜를 히브리어로 서식을 지정하려면:

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const hebrewCalendar = Temporal.Calendar.from('hebrew');
const hebrewDate = gregorianDate.toPlainDate(hebrewCalendar);

const formatter = new Intl.DateTimeFormat('he-IL-u-ca-hebrew', { // 히브리어(이스라엘), 히브리력 사용
  year: 'numeric',
  month: 'long',
  day: 'numeric',
});

console.log(formatter.format(hebrewDate));

효과적인 날짜 서식 지정을 위한 팁:

• 사용자의 선호 언어와 지역을 정확하게 반영하는 로케일 문자열을 사용하십시오.
• 문맥에 적합한 서식 옵션을 선택하십시오 (예: 간결한 표시를 위한 짧은 날짜 형식, 상세한 프레젠테이션을 위한 긴 날짜 형식).
• 정확성과 가독성을 보장하기 위해 다양한 로케일에서 서식을 테스트하십시오.

여러 달력 간의 날짜 연산 수행

Temporal API는 날짜 연산에 탁월합니다. 그레고리력이 아닌 달력으로 작업할 때도 `Temporal.PlainDate` 객체에서 일, 월 또는 연도를 더하거나 뺄 수 있습니다.

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = gregorianDate.toPlainDate(islamicCalendar);

// 이슬람 날짜에 30일 더하기
const futureIslamicDate = islamicDate.add({ days: 30 });

console.log(`Original Islamic Date: ${islamicDate.year}-${islamicDate.month}-${islamicDate.day}`);
console.log(`Islamic Date + 30 days: ${futureIslamicDate.year}-${futureIslamicDate.month}-${futureIslamicDate.day}`);

// 미래의 이슬람 날짜를 다시 그레고리력으로 변환
const futureGregorianDate = futureIslamicDate.toPlainDate('iso8601');
console.log(`Equivalent Gregorian Date: ${futureGregorianDate.toString()}`);

날짜 연산에 대한 주요 고려사항:

• `add()` 및 `subtract()` 메서드는 새로운 `Temporal.PlainDate` 객체를 반환하며, 원본 객체를 수정하지 않습니다.
• 월이나 연도를 더하거나 뺄 때, Temporal API는 윤년 및 월 길이에 대한 달력별 규칙을 처리합니다.
• 연산을 수행할 때 잠재적인 날짜 오버플로우나 언더플로우에 유의하십시오. Temporal API는 일반적으로 해당 달력 내에서 가장 가까운 유효한 날짜로 조정합니다.

모호한 날짜 처리

어떤 경우에는 달력 간 변환 시 날짜가 모호할 수 있습니다. 이는 특정 날짜가 대상 달력에 존재하지 않거나 대상 달력의 여러 날짜가 원본 날짜에 해당할 수 있을 때 발생할 수 있습니다. Temporal은 이러한 상황을 원활하게 처리하며, 일반적으로 가장 가까운 유효한 날짜를 반환합니다.

예를 들어, 그레고리력 월말에 가까운 그레고리력 날짜를 이슬람력으로 변환하는 경우, 해당 이슬람력 월이 더 짧을 수 있습니다. Temporal은 결과적인 이슬람 날짜를 해당 월의 마지막 날로 자동 조정합니다.

오류 처리 및 유효성 검사

Temporal API는 견고하지만, 예기치 않은 동작을 방지하기 위해 적절한 오류 처리 및 유효성 검사를 구현하는 것이 중요합니다. 고려해야 할 몇 가지 일반적인 시나리오는 다음과 같습니다:

• 잘못된 달력 이름: `Temporal.Calendar.from()`에 잘못된 달력 이름을 제공하면 `RangeError`가 발생합니다. 이 오류를 포착하고 사용자 친화적인 메시지를 제공하십시오.
• 잘못된 날짜 형식: 잘못된 날짜 문자열로 `Temporal.PlainDate`를 만들려고 하면 `RangeError`가 발생합니다. `Temporal.PlainDate.from()`에 전달하기 전에 날짜 문자열의 유효성을 검사하십시오.
• 지원되지 않는 작업: 일부 달력별 작업은 Temporal API에서 지원되지 않을 수 있습니다. 사용 중인 특정 달력에 대한 설명서를 확인하십시오.

여러 달력 간 날짜 매핑을 위한 모범 사례

여러 달력 간 날짜 매핑 작업 시 정확성과 유지 관리성을 보장하려면 다음 모범 사례를 따르십시오:

• Temporal API 사용: Temporal API는 달력 변환을 처리하는 표준화되고 견고한 방법을 제공합니다. 이 목적을 위해 레거시 JavaScript `Date` 객체를 사용하지 마십시오.
• 달력을 명시적으로 지정: `Temporal.PlainDate` 객체를 생성할 때 항상 달력을 명시적으로 지정하십시오. 이는 모호성을 방지하고 올바른 달력 규칙이 적용되도록 보장합니다.
• 올바른 이슬람력 변형 선택: 다양한 이슬람력 구현 간의 차이점을 이해하고 사용 사례에 가장 적합한 것을 선택하십시오.
• 국제화(i18n) 사용: `Intl.DateTimeFormat` API를 활용하여 로케일에 맞는 방식으로 날짜 서식을 지정하십시오.
• 오류 처리 구현: 잘못된 달력 이름, 날짜 형식 및 기타 잠재적인 문제를 포착하기 위해 강력한 오류 처리를 구현하십시오.
• 철저한 테스트: 정확성과 호환성을 보장하기 위해 다양한 날짜와 로케일로 코드를 테스트하십시오.
• 최신 정보 유지: Temporal API는 계속 발전하고 있습니다. 최신 사양과 브라우저 구현에 대한 최신 정보를 유지하십시오.

결론

JavaScript의 Temporal API는 날짜와 달력을 처리하는 방식을 혁신하여, 여러 달력 간의 날짜 매핑을 수행하는 강력하고 표준화된 방법을 제공합니다. 다양한 달력 시스템의 미묘한 차이를 이해하고 Temporal API를 효과적으로 활용함으로써 개발자는 다양한 문화 및 종교적 요구에 부응하는 글로벌 인식이 가능한 애플리케이션을 구축할 수 있습니다. 프로젝트에서 더 포괄적이고 정확한 날짜 처리 솔루션을 만들기 위해 Temporal API를 도입하십시오.

이 가이드는 JavaScript Temporal API를 사용한 달력 변환에 대한 포괄적인 개요를 제공했습니다. 가장 최신 정보와 상세한 사양은 공식 Temporal API 설명서를 참조하십시오.